<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Layering Decorators - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/learning.form.decorators.layering.html">Inglês (English)</a></li>
    <li><a href="../pt-br/learning.form.decorators.layering.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.form.decorators.simplest.html">Decorator Basics</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.form.decorators.html">Understanding and Using Zend Form Decorators</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.form.decorators.individual.html">Rendering Individual Decorators</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="learning.form.decorators.layering" class="section"><div class="info"><h1 class="title">Layering Decorators</h1></div>
    

    <p class="para">
        If you were following closely in <a href="learning.form.decorators.simplest.html" class="link">the
            previous section</a>, you may have noticed that a decorator&#039;s
         <span class="methodname">render()</span> method takes a single argument,
        <var class="varname">$content</var>. This is expected to be a string.
         <span class="methodname">render()</span> will then take this string and decide to either replace
        it, append to it, or prepend it. This allows you to have a chain of decorators -- which
        allows you to create decorators that render only a subset of the element&#039;s metadata, and
        then layer these decorators to build the full markup for the element.
    </p>

    <p class="para">
        Let&#039;s look at how this works in practice.
    </p>

    <p class="para">
        For most form element types, the following decorators are used:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <span class="classname">ViewHelper</span> (render the form input using one of the standard
                form view helpers).
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">Errors</span> (render validation errors via an unordered list).
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">Description</span> (render any description attached to the element;
                often used for tooltips).
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">HtmlTag</span> (wrap all of the above in a
                <em class="emphasis">&lt;dd&gt;</em> tag.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">Label</span> (render the label preceding the above, wrapped in a
                <em class="emphasis">&lt;dt&gt;</em> tag.
            </p>
        </li>
    </ul>

    <p class="para">
        You&#039;ll notice that each of these decorators does just one thing, and operates on one
        specific piece of metadata stored in the form element: the <span class="classname">Errors</span>
        decorator pulls validation errors and renders them; the <span class="classname">Label</span>
        decorator pulls just the label and renders it. This allows the individual decorators to be
        very succinct, repeatable, and, more importantly, testable.
    </p>

    <p class="para">
        It&#039;s also where that <var class="varname">$content</var> argument comes into play: each decorator&#039;s
         <span class="methodname">render()</span> method is designed to accept content, and then either
        replace it (usually by wrapping it), prepend to it, or append to it.
    </p>

    <p class="para">
        So, it&#039;s best to think of the process of decoration as one of building an onion from the
        inside out.
    </p>

    <p class="para">
        To simplify the process, we&#039;ll take a look at the example from <a href="learning.form.decorators.simplest.html" class="link">the previous section</a>. Recall:
    </p>

    <pre class="programlisting brush: php">
class My_Decorator_SimpleInput extends Zend_Form_Decorator_Abstract
{
    protected $_format = &#039;&lt;label for=&quot;%s&quot;&gt;%s&lt;/label&gt;&#039;
                       . &#039;&lt;input id=&quot;%s&quot; name=&quot;%s&quot; type=&quot;text&quot; value=&quot;%s&quot;/&gt;&#039;;

    public function render($content)
    {
        $element = $this-&gt;getElement();
        $name    = htmlentities($element-&gt;getFullyQualifiedName());
        $label   = htmlentities($element-&gt;getLabel());
        $id      = htmlentities($element-&gt;getId());
        $value   = htmlentities($element-&gt;getValue());

        $markup  = sprintf($this-&gt;_format, $id, $label, $id, $name, $value);
        return $markup;
    }
}
</pre>


    <p class="para">
        Let&#039;s now remove the label functionality, and build a separate decorator for that.
    </p>

    <pre class="programlisting brush: php">
class My_Decorator_SimpleInput extends Zend_Form_Decorator_Abstract
{
    protected $_format = &#039;&lt;input id=&quot;%s&quot; name=&quot;%s&quot; type=&quot;text&quot; value=&quot;%s&quot;/&gt;&#039;;

    public function render($content)
    {
        $element = $this-&gt;getElement();
        $name    = htmlentities($element-&gt;getFullyQualifiedName());
        $id      = htmlentities($element-&gt;getId());
        $value   = htmlentities($element-&gt;getValue());

        $markup  = sprintf($this-&gt;_format, $id, $name, $value);
        return $markup;
    }
}

class My_Decorator_SimpleLabel extends Zend_Form_Decorator_Abstract
{
    protected $_format = &#039;&lt;label for=&quot;%s&quot;&gt;%s&lt;/label&gt;&#039;;

    public function render($content)
    {
        $element = $this-&gt;getElement();
        $id      = htmlentities($element-&gt;getId());
        $label   = htmlentities($element-&gt;getLabel());

        $markup = sprintf($this-&gt;_format, $id, $label);
        return $markup;
    }
}
</pre>


    <p class="para">
        Now, this may look all well and good, but here&#039;s the problem: as written currently, the last
        decorator to run wins, and overwrites everything. You&#039;ll end up with just the input, or
        just the label, depending on which you register last.
    </p>

    <p class="para">
        To overcome this, simply concatenate the passed in <var class="varname">$content</var> with the
        markup somehow:
    </p>

    <pre class="programlisting brush: php">
return $content . $markup;
</pre>


    <p class="para">
        The problem with the above approach comes when you want to programmatically choose whether
        the original content should precede or append the new markup. Fortunately, there&#039;s a
        standard mechanism for this already; <span class="classname">Zend_Form_Decorator_Abstract</span> has
        a concept of placement and defines some constants for matching it. Additionally, it allows
        specifying a separator to place between the two. Let&#039;s make use of those:
    </p>

    <pre class="programlisting brush: php">
class My_Decorator_SimpleInput extends Zend_Form_Decorator_Abstract
{
    protected $_format = &#039;&lt;input id=&quot;%s&quot; name=&quot;%s&quot; type=&quot;text&quot; value=&quot;%s&quot;/&gt;&#039;;

    public function render($content)
    {
        $element = $this-&gt;getElement();
        $name    = htmlentities($element-&gt;getFullyQualifiedName());
        $id      = htmlentities($element-&gt;getId());
        $value   = htmlentities($element-&gt;getValue());

        $markup  = sprintf($this-&gt;_format, $id, $name, $value);

        $placement = $this-&gt;getPlacement();
        $separator = $this-&gt;getSeparator();
        switch ($placement) {
            case self::PREPEND:
                return $markup . $separator . $content;
            case self::APPEND:
            default:
                return $content . $separator . $markup;
        }
    }
}

class My_Decorator_SimpleLabel extends Zend_Form_Decorator_Abstract
{
    protected $_format = &#039;&lt;label for=&quot;%s&quot;&gt;%s&lt;/label&gt;&#039;;

    public function render($content)
    {
        $element = $this-&gt;getElement();
        $id      = htmlentities($element-&gt;getId());
        $label   = htmlentities($element-&gt;getLabel());

        $markup = sprint($this-&gt;_format, $id, $label);

        $placement = $this-&gt;getPlacement();
        $separator = $this-&gt;getSeparator();
        switch ($placement) {
            case self::APPEND:
                return $markup . $separator . $content;
            case self::PREPEND:
            default:
                return $content . $separator . $markup;
        }
    }
}
</pre>


    <p class="para">
        Notice in the above that I&#039;m switching the default case for each; the assumption will be
        that labels prepend content, and input appends.
    </p>

    <p class="para">
        Now, let&#039;s create a form element that uses these:
    </p>

    <pre class="programlisting brush: php">
$element = new Zend_Form_Element(&#039;foo&#039;, array(
    &#039;label&#039;      =&gt; &#039;Foo&#039;,
    &#039;belongsTo&#039;  =&gt; &#039;bar&#039;,
    &#039;value&#039;      =&gt; &#039;test&#039;,
    &#039;prefixPath&#039; =&gt; array(&#039;decorator&#039; =&gt; array(
        &#039;My_Decorator&#039; =&gt; &#039;path/to/decorators/&#039;,
    )),
    &#039;decorators&#039; =&gt; array(
        &#039;SimpleInput&#039;,
        &#039;SimpleLabel&#039;,
    ),
));
</pre>


    <p class="para">
        How will this work? When we call  <span class="methodname">render()</span>, the element will iterate
        through the various attached decorators, calling  <span class="methodname">render()</span> on each.
        It will pass an empty string to the very first, and then whatever content is created will be
        passed to the next, and so on:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                Initial content is an empty string: &#039;&#039;.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                &#039;&#039; is passed to the <span class="classname">SimpleInput</span> decorator, which then
                generates a form input that it appends to the empty string: <em class="emphasis">&lt;input
                    id=&quot;bar-foo&quot; name=&quot;bar[foo]&quot; type=&quot;text&quot; value=&quot;test&quot;/&gt;</em>.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                The input is then passed as content to the <span class="classname">SimpleLabel</span>
                decorator, which generates a label and prepends it to the original content; the
                default separator is a <b><tt>PHP_EOL</tt></b> character, giving us this:
                <em class="emphasis">&lt;label for=&quot;bar-foo&quot;&gt;\n&lt;input id=&quot;bar-foo&quot; name=&quot;bar[foo]&quot;
                    type=&quot;text&quot; value=&quot;test&quot;/&gt;</em>.
            </p>
        </li>
    </ul>

    <p class="para">
        But wait a second! What if you wanted the label to come after the input for some reason?
        Remember that &quot;placement&quot; flag? You can pass it as an option to the decorator. The easiest
        way to do this is to pass an array of options with the decorator during element creation:
    </p>

    <pre class="programlisting brush: php">
$element = new Zend_Form_Element(&#039;foo&#039;, array(
    &#039;label&#039;      =&gt; &#039;Foo&#039;,
    &#039;belongsTo&#039;  =&gt; &#039;bar&#039;,
    &#039;value&#039;      =&gt; &#039;test&#039;,
    &#039;prefixPath&#039; =&gt; array(&#039;decorator&#039; =&gt; array(
        &#039;My_Decorator&#039; =&gt; &#039;path/to/decorators/&#039;,
    )),
    &#039;decorators&#039; =&gt; array(
        &#039;SimpleInput&#039;
        array(&#039;SimpleLabel&#039;, array(&#039;placement&#039; =&gt; &#039;append&#039;)),
    ),
));
</pre>


    <p class="para">
        Notice that when passing options, you must wrap the decorator within an array; this hints to
        the constructor that options are available. The decorator name is the first element of the
        array, and options are passed in an array to the second element of the array.
    </p>

    <p class="para">
        The above results in the markup <em class="emphasis">&lt;input id=&quot;bar-foo&quot; name=&quot;bar[foo]&quot; type=&quot;text&quot;
            value=&quot;test&quot;/&gt;\n&lt;label for=&quot;bar-foo&quot;&gt;</em>.
    </p>

    <p class="para">
        Using this technique, you can have decorators that target specific metadata of the element
        or form and create only the markup relevant to that metadata; by using mulitiple decorators,
        you can then build up the complete element markup. Our onion is the result.
    </p>

    <p class="para">
        There are pros and cons to this approach. First, the cons:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                More complex to implement. You have to pay careful attention to the decorators you
                use and what placement you utilize in order to build up the markup in the correct
                sequence.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                More resource intensive. More decorators means more objects; multiply this by the
                number of elements you have in a form, and you may end up with some serious resource
                usage. Caching can help here.
            </p>
        </li>
    </ul>

    <p class="para">
        The advantages are compelling, though:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                Reusable decorators. You can create truly re-usable decorators with this technique,
                as you don&#039;t have to worry about the complete markup, but only markup for one or a
                few pieces of element or form metadata.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                Ultimate flexibility. You can theoretically generate any markup combination you want
                from a small number of decorators.
            </p>
        </li>
    </ul>

    <p class="para">
        While the above examples are the intended usage of decorators within
        <span class="classname">Zend_Form</span>, it&#039;s often hard to wrap your head around how the
        decorators interact with one another to build the final markup. For this reason, some
        flexibility was added in the 1.7 series to make rendering individual decorators possible --
        which gives some Rails-like simplicity to rendering forms. We&#039;ll look at that in the next
        section.
    </p>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.form.decorators.simplest.html">Decorator Basics</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.form.decorators.html">Understanding and Using Zend Form Decorators</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.form.decorators.individual.html">Rendering Individual Decorators</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="learning.html">Learning Zend Framework</a></li>
  <li class="header up"><a href="learning.form.decorators.html">Understanding and Using Zend Form Decorators</a></li>
  <li><a href="learning.form.decorators.intro.html">Introduction</a></li>
  <li><a href="learning.form.decorators.simplest.html">Decorator Basics</a></li>
  <li class="active"><a href="learning.form.decorators.layering.html">Layering Decorators</a></li>
  <li><a href="learning.form.decorators.individual.html">Rendering Individual Decorators</a></li>
  <li><a href="learning.form.decorators.composite.html">Creating and Rendering Composite Elements</a></li>
  <li><a href="learning.form.decorators.conclusion.html">Conclusion</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>